Method Euphoria 3.0.0
© October2010 by Michael A. Nelson
mikestar13@sbcglobal.net
TABLE OF CONTENTS
WHAT IS METHOD EUPHORIA?
Method Euphoria is a library written in the Euphoria programming language (version 2.5).
It is intended to allow programmers to use object-oriented programming in
Euphoria, by allowing the definition of classes, and the creation and use of
objects based on these classes.
Method Euphoria was designed to be powerful and secure, even at the cost of
complexity. Method Euphoria is intended for the advanced OOP programmer.
Method Euphoria is built around the idea that methods are the foundation of OOP programming: properties and events are implemented via methods.
FEATURES OF METHOD EUPHORIA
- Java-style Object Oriented Programming with single inheritance and interfaces.
- Automatic run-time polymorphism.
- Exception handling for error recovery.
- Methods may have public, protected, or private access.
- Instance and class properties and methods.
- Objects can only be accessed through the routines provided by Method Euphoria;
direct access is impossible, providing excellent security.
- Packages for classes to provide globally unique class names.
- Classes as well as instances are accessed by references, and can take advantage of
Euphoria namespacing.
- Objects can be converted to and restored from coded byte sequences for storage in
a file, transmission over a network or the internet, etc.
- Extensive validation capability, including type checks which throw an exception in
case of failure rather than aborting.
- Built-in event handling with multiple event handlers.
OBJECT ORIENTED PROGRAMMING IN METHOD
EUPHORIA
The fundamental concept of object-oriented programming (OOP) is the object.
An object may be thought of as a semi-independent program containing data
(properties) and routines (methods). An object represents an entity: a truck, a
checking account, a character in a role-playing game, etc. Properties represent
attributes of these entities: a truck's weight limit, a checking account's
balance, a character's experience points. Methods
represent actions performed by or on the entity: a truck turns, a check is
debited to a checking account, and a character attacks a monster. One common
way of expressing this it an object consists of its state (properties) and its behavior (methods).
Method Euphoria also supports
events. Events are a specialized form of methods.
Because object is a Euphoria data
type, from here on an object in the OOP sense above will be called an entity.
Classes are types of entities: trucks, checking accounts, characters.
Classes are blueprints for the creation of entities. Classes may also have
properties and methods: attributes and actions pertaining to the whole class
rather than to a particular entity. The simplest example would be a class
property used as a counter to determine the number of entities of that class
which have been created.
In Method Euphoria, classes are also entities (see Entities).
A class may be derived from another class and inherit properties and methods
from that class. The class derived from is called a superclass; the
derived class is called a subclass. For example, if there is a class Car, you could define
Police_Car as a
subclass of Car, inheriting all the
properties and methods
of Car and adding new properties and methods
to represent attributes and actions of police cars which do not apply to normal
cars.
Inherited methods may be redefined by
a subclass; inherited properties may not be redefined as such, but their
accessor methods may be redefined.
In OOP terminology, the kind of redefinition above is called
overriding. Method
Euphoria does not support method overloading,
which refers to defining more than one method with the same name in a class,
but with a different number of parameters or different parameter types.
PROGRAM CONTEXT
Method Euphoria defines three program contexts—initialization, class
definition, and method. A Method Euphoria program begins in initialization,
where classes may be defined. Class
definition context means a class definition is in progress. The program
returns to initialization context when a class definition is completed.
When all class definitions are complete, the
program will call the procedure main_program. This
takes a class as its parameter and calls that class’ main method. (Alternatively, start_program can be used.) The program will remain in method context until program termination.
Many Method Euphoria routines can only be used in certain program contexts. Also, some
Method Euphoria routines are not allowed if an exception is pending. For
information on specific routines, see the alphabetical listing.
POLYMORPHISM
There are various definitions of polymorphism. The definition used in Method
Euphoria is as follows: Assume Alpha is a class and Beta is a subclass of
Alpha. Whenever an Alpha instance or the Alpha class may be used, a Beta
instance or the Beta class may be used in its place. The definition is not
reversible: it may be possible to use an Alpha instance or the Alpha class in
place of a Beta instance or the Beta class, but this is not required.
As a logical consequence of this definition, if Beta overrides an Alpha
method, the Beta method must not have more restrictive access than the
overridden Alpha method.
ENTITIES
An entity consists of two parts--a handle and a value. The handle is a
reference with which the value may be manipulated by Method Euphoria.
Internally, a handle is a three-integer sequence. The first element is the Euphoria's largest negative integer,
the second indicates the location in the local sequence in which
Method Euphoria maintains the values of all instance entities (or 0 if the
entity is a class), and the third indicates the class. The chance of
normal data reproducing this by chance is virtually zero, so if entity(x)
returns TRUE, x is an entity.
However, sequence(x) will of course also return TRUE.
Because an entity is a reference, x=y where x and y are entities results in
only the handle being copied, x and y share the same internal data and a change
in one will result in a change in the other. To make an actual copy of an
entity, use the entity's clone
method.
Method Euphoria defines three types of entities—instance, class, and deleted:
An instance entity is a particular entity belonging to a class. This is the
typical object in Object Oriented
Programming.
For classes, see below.
A deleted entity is an instance which no longer contains data due to having
been deleted. For type checking purposes, a deleted entity is not treated as an entity.
CLASSES
A class is an entity which is used as a blueprint for creating instances.
There are three types of classes:
- Normal classes: Method Euphoria
provides a universal base class named Entity
with special methods inherited by every normal class. Entity has no superclass; normal classes must have exactly one
superclass.
- Interfaces: Method Euphoria provides a
universal base class named Interface which
is the superclass of all interfaces. Interface
has no superclass; interfaces may have one or more superclasses. (See Interfaces.)
- Exceptions: Method Euphoria provides a
universal base class named Exception which
is the superclass of all exceptions. Exception
has no superclass; exceptions must have exactly one superclass. (See Exceptions and Exception Handling.)
PACKAGES
It is essential that all classes used in a program must be distinguishable
from each other. A class is identified by its handle and by its name. It is no
problem if classes from different sources might have the same name for their
handle constants: Euphoria namespacing will resolve
the issue. But for saving and restoring entities, handles cannot be used as
they are dependent on the particular program and often a particular run of that
program. For saving and restoring entities, the class name is used. It is
entirely likely that class names will be duplicated. In order to resolve these
ambiguities, Method Euphoria implements a package concept. Classes are grouped
into packages and Method Euphoria will allow two classes with the same name to
be used in a program if and only if the two classes belong to different
packages. The package procedure
defines a package; any class defined from the point that package is encountered
until an end_ package procedure is
encountered are part of that package. Packages may be nested. If a class is
defined before any package procedure is encountered, it will not belong to any
package (this can be interpreted as belonging to an anonymous default package).
Whenever a class is used, its name expressed as a string may be used in place of its handle constant. This will allow the solution of some namespace problems. The fully qualifed class name (for example "ME_Std_Lib.Containers.Map") will always work. The class name alone is sufficient:
- In class, interface, or exception where the class is in the same package as the class being defined.
- In all cases during the execution of a method, if the class is in the same package as the class which defined the method currently being executed.
- If the class is in the ME_Kernel or ME_Std_Lib packages, unless this results in a name clash with case 1 or 2.
ACCESS RIGHTS
Access rights control access to methods of a class. The three types of
access are:
- PUBLIC: the method may be called
by a method of any class.
- PROTECTED: the method may be
called by a method of the class which defines the method or a superclass of
that class. A method of a subclass of the defining class may call the method if
the target belongs to the subclass or of one of the subclass's subclasses, but
may not call the method otherwise.
- PRIVATE: the method may be called
by a method of the class which defines the method or a superclass of that
class.
Suppose we have four classes A, B,
C, and D where B is a subclass of A, C is a subclass of B and D is a subclass
of C. Class B defines three instance methods: x with public access, y with
protected access, and z with private access. An unrelated class' method may
call only method x. A class A or class B method can call all three methods. A
class C method can call x, and can call the y method with an instance of class
C or D as its target, but cannot call the y method with an instance of B as its
target. A class D method can call x and can call the y method with an instance
of D as its target, but cannot call the y method with an instance of B or C as
its target.
PROPERTIES
Properties represent the state of an entity. In Method Euphoria, properties
can only be accessed by methods defined by the class which defines the
property. Properties are inherited from
superclasses, but overriding is not allowed. If less restrictive access is
needed, accessor methods must be defined. Normally, there are two accessor
methods per property, a getter
to read the property and a setter to write it. The property
procedure can cause accessor methods to be generated for you automatically. See
also get_property and set_property.
METHODS
Methods represent the behavior of an entity. Methods are inherited from
superclasses and can be overridden.
The universal base class Entity provides some special methods. See method and call_method.
METHOD OVERRIDING
Methods inherited from a superclass can be overridden. To override a method,
define an instance method or a class method (as the case may be) with the same name in the subclass. The overriding method must
have the same access rights or less restrictive access rights than the
overridden method. Thus a private method may be overridden by a public method,
but a public method may not be overridden by a private method. Sometimes the
whole purpose of overriding is to use less restrictive access. An overridden
method can be called by using call_super in the overriding method.
Overriding is the mechanism which makes polymorphism work. For example: A is a class and B is a
subclass of A. A defines an instance method x
and B overrides x with its own
method. Then
call_method(z,"x",{15})
will call A's method x if z is an instance
of A, but will call B's method x if z is an instance of B.
SPECIAL METHODS
The universal base class Entity provides
three special methods which are inherited by every class:
- Class method new: this method creates a new instance entity of the calling class.
- Instance method clone: this method
creates a shallow copy of its target instance. In a shallow copy, if a property
of the instance is also an instance, only the reference is copied. If a deep
copy (properties which are instances are cloned) is needed for instances of a
given class, that class can override the clone
method.
- Instance method delete: this method destroys its target instance. The delete
method reclaims memory used by an instance which is no longer needed. A class
may override the delete method to release resources such as file or window
handles used by the instance, or to delete instances which are contained in the
instance.
These methods are protected in Entity. Usually you will want to override new
and delete in your class to make them public. If you want to be able to copy
instances of your class, override clone to make it public.
There are cases where you may want to leave these methods
protected to control the creation, destruction, or copying of your class's
instances.
AUTOMATIC METHOD CALLS
Method Euphoria calls certain methods automatically without the use of call_method.
Automatic calls ignore access rights. This only applies to the direct call--any
method calls by the called method work normally. Method Euphoria makes the
following automatic method calls:
- main_program and start_program call the
class method initialize for each class that defines one, in class
definition order.
- main_program calls the class method main of its parameter class.
- main_program, end_program, and
fatal_error call the class method terminate for each class that defines one, in reverse class definition order.
- call_method and call_super call the instance or class method undefined_method (if the target class or superclass defines one) when an attempt is made to call a method that the target class or superclass does not define.
- serialize may call the serialize instance method.
- deserialize may call the deserialize instance method.
The instance method undefined_method and the class methods initialize, terminate, and undefined_method may only be called automatically, it an error to attempt to call them via call_method. The class method main may be called via call_method. (This might be useful to restart a program.) Calling the methods from overriding subclass methods via call_super is permissible.
The instance methods serialize and deserialize may not be called via call_method or call_super. See Serialization for details about these methods.
Method Euphoria ignores the return values of main, initialize, terminate, serialize, and deserialize.
EVENTS
Events represent specialized behavior of an entity. Each event may have one
or more handlers assigned during the run of the program. (If an event is raised
before any handlers have been assigned, nothing happens.)
When an event x is defined by a
class, an instance property also named x is
defined, as are three instance methods: get_x, which
returns the sequence of event handlers; set_x, which sets
the event handlers for the event; and a method also named x which is used to raise the event.
Event handlers are instances of the Method_Wrapper class.
A method wrapper indirectly calls the method it was linked to when it was
created. (Similar to a function pointer in C or a delegate in C#.)
When the event is raised by calling method x, each handler is called in the order in which they appear in the
sequence of handlers. Each handler will be passed the target instance of the
event, the name of the event, and all parameters that were passed to x. If a handler returns a value other
than NOTHING or throws an exception,
subsequent handlers are not called.
INTERFACES
Interfaces are special classes containing lists of instance and class
methods. A class which defines each instance and class method of an interface
(directly or by inheritance) as a public method is said to implement that
interface. (Method Euphoria does not recognize this automatically, it must be
declared in the class
function defining the class.) Interfaces express relationships not based on
inheritance. For example, in a role playing game program, characters, weapons,
gold pieces, magic items, etc. do not have inheritance relationships with each
other, but all might implement an interface which lists the method neededs to save the
game state to disk and to restore it from disk. It is possible to define an
interface with no methods to act as a tag. The standard library Containers package
defines several tag interfaces.
Interfaces are defined using interface. In contrast to normal classes and
exceptions, interfaces allow multiple inheritence: an
interface may have one or more superclasses.
EXCEPTIONS AND EXCEPTION HANDLING
Exceptions are provided for the handling of recoverable errors and other
exceptional conditions. The procedure fatal_error should
be used to display error messages for non-recoverable errors.
Method Euphoria uses a crash routine which calls fatal_error to do proper cleanup.
Exceptions are special classes which form a hierarchy. The exception Exception is predefined in Method Euphoria and
has no superclass. Method Euphoria also
predefines several other exceptions. Exceptions are defined using exception and must specify a superclass.
When your program encounters an error, use throw to signal an exception. That exception becomes the pending exception if no other exception is pending. If another exception is pending, the program terminates: only one exception may be pending at a time. If a method is called while an exception is pending, the pending exception is saved and is not pending during the execution of that method. When the method returns, the saved exception once again becomes pending.
If a method returns while an exception is pending, the exception remains pending. If the calling method has a saved exception, this results in program termination as if an exception had been thrown while another is pending.
For the purpose of exception handling, serialize and deserialize are treated as methods.
Several functions allow you to test for an exception without processing it:
success returns TRUE if no exception
is pending and FALSE if there is a pending exception; failure returns TRUE if an exception is
pending and FALSE if there is not; pending returns the pending exception if there is one and returns NOTHING if there is not.
To process an exception use catch. This function determines
whether an exception is pending: if not, it returns FALSE. If an exception is
pending, catch determines if the
exception given as its parameter is the same exception as the pending exception
or is a superclass of the pending exception. If so catch returns TRUE and clears the pending exception, otherwise it
returns FALSE. Therefore catch(Exception)
will catch any exception, as Exception is a superclass of
all exceptions.
When you catch an exception and need to know the exact exception, use caught: this
returns the last exception processed by catch,
but returns NOTHING if there is none. If after catching an exception you want to throw the
same exception again, the procedure rethrow is used. This makes
the last caught exception the pending exception again. If rethrow is used when no
exception has been caught, nothing happens.
VALIDATION
Method Euphoria provides an alternative to standard Euphoria type checking, in which a
type check failure can throw an exception rather than abort the program
immediately. This is used primarily for type checking method parameters.
Validation also handles optional parameters.
Method Euphoria predefines special
type checking functions for boolean, integer, atom, object,
sequence, string and identifier. Sequence and object fail if the parameter is an entity.
Two types are predefined for use in dynamic type checking: type_specifier and anything. Type_specifer allows a type to be passed as parameter. An example is in the Container class. A type specifier is passed as a parameter to Container's constructor to specify the allowable type for elements of the container. Anything is a type that does no type checking.
A generic entity type is
predefined, as are instance and class.
These types are used by the
validate procedure. This procedure type checks its parameter
and throws the Type_Check_Failure exception
if the type check fails. The call_method and call_super functions pass the
special value NOTHING if an expected
method parameter is not provided. If the parameter is optional, validate will not throw an exception in this case; if it is required, it will throw the Missing_Parameter
exception.
You
may define additional type checks to be used in validation by using the register_type procedure.
SERIALIZATION
Instances
can be converted into coded byte sequences. These sequences can be stored to a
file, or transmitted over a network or the internet. Use serialize
to create the coded sequence and use deserialize to recreate the instance. Instances can be shared by the same program running on
different machines or by different programs on the same or different machines
if both programs define the instance’s class and the classes of any of the instance’s property values which are themselves
entities.
For
most classes, serialize and deserialize will be sufficient. If custom serialization is required, define a serialize instance method taking no parameters. Your serialize method can assign property values to be serialized by using set_property with serialized as its target. To prevent the serialization of an instance but allow the serialization of any instance it is contained in to continue, use cancel_serialize: this causes the serialization of NOTHING rather than the instance. To abort the entire serialization process, throw an exception.
If custom deserialization is required, define a deserialize instance method taking no parameters. Your deserialize method can use this to read or change the property values of the deserialized instance. To prevent the deserialization of an instance but allow the deserialization of any instance it is contained in to continue, call the delete instance method with this as its target: this returns NOTHING rather than the instance. To abort the entire deserialization process, throw an exception.
Euphoria integers, atoms, and sequences can also be serialized. Classes can be serialized:
when a class is serialized, its property values are not serialized.
CLASS DESIGN IN METHOD EUPHORIA
A class or several related classes can be defined in an include file or in the program file.
Consider the properties, methods, and events your class needs. Determine if an existing
class can be used as a superclass and provide some or most of the properties,
methods, and events by inheritance. Consider what interfaces should be
implemented and if necessary, define new ones.
Give careful thought to the creation, copying, and destruction of the class's
instances.
Consider error handling and which exceptions will be used, defining new ones if
necessary.
Open the class definition by using class. The class handle returned by class should normally be assigned to a
global constant; however a local constant could be used if it is desired to
have the class usable only in the file which defines it.
Register each property by using property.
If a class property is intended as a constant, use a public getter method and no
setter method. If the value of the constant will be the same in this class and
all of its subclasses, just set the default value to the constant value, or set
the value in the class' initialize class method. If subclasses will have different constant values for this property, have the subclass’ initialize method pass the value passed to the class’ initialize method as a parameter. Null
methods are a good alternative, see below.
Code methods as functions or procedures taking the
appropriate number of object parameters (which may be none). If the method
overrides a superclass method, the superclass method may be called by using call_super
if the superclass method is not private.
Register each method using method.
Most methods will be public. Methods used for internal use only will be
private. Methods not generally available but needed by
subclasses will be protected.
Register events with event.
The null_method procedure is used to define a method
which does nothing and returns a specified value. This might be useful if your
class must have a method to implement an interface method but don't really need
the method. It is also a simple way to define a method which returns a
constant.
The
super_method procedure is used to override
superclass methods: it defines a method that simply passes its parameters to
the overridden superclass method and returns the superclass method's return
value.
Code the constructor as a class method named new
which returns a newly-created instance or throws an exception and returns NOTHING in case of failure. The superclass constructor must be called (by using call_super). Normally,
you will specify public access for the constructor but may use protected access
to control the creation of instances of the class. If no initialization needs
to be done, super_method may be used for the class' new method. Note that if the class is an immediate subclass of Entity, you
must override Entity's new class
method to provide public access.
If copying of instances is to be done, using the clone instance method inherited from Entity will be sufficient if a shallow copy (if the value of a
property is an instance, only the handle is copied) is acceptable. Note that if
the class is an immediate subclass of Entity, you must override Entity's clone instance method to provide public access. If a deep copy (if the value of a property is an instance, a copy of that instance is made) is needed, or any kind of error checking or conditional copying is to be done, define the copy constructor as an instance method named clone which returns a copied instance or
throws an exception and returns NOTHING in case of failure. The superclass copy constructor must be called (by using call_super).
A destructor is often not necessary: the delete method inherited from Entity will very often be sufficient. Note that if the class is an immediate
subclass of Entity, you must override
Entity's delete instance method to provide public access. A destructor is necessary if instances contain system resources such as file or window handles: the destructor must release these. A destructor may be necessary if the instance can contain other instances. It may be desirable to ensure that these are destroyed when the containing instance is
destroyed. In general, a reference to an external instance should not be
deleted, while an instance created for internal use should be. If a destructor
is needed, code it as an instance method named delete which returns NOTHING or
throws an exception and returns the target instance in case of failure. The
superclass destructor must be called (by using call_super).
If the class requires initialization, code a class method named initialize. This will be called automatically by main_program or start_program.
If a class requires cleanup after the normal run of the program or in case of a fatal error, code a class method terminate. This will be called when the program ends, if main_program or start_program has been executed. Note that terminate will always be called in this case, even if a fatal error occurs during the class' initialize method.
Do not call a method's implementing routine directly rather than than through call_method. This would defeat Method Euphoria’s access control and stack trace facilities. (Code Warriors can ignore this if they are careful--for example to emulate friend classes or to squeeze maximum performance out of private methods.)
THE APPLICATION CLASS
The application class is the class whose main class method is called by main_program. Typically,
this will be the last class defined before main_program is called. It will
inherit directly from Entity and will
have no properties or instance methods. In some cases, the only method will be main. If there is a lot of initialization to be done, the initialize
class method is a good place for it—when the application class is the last
class to be defined, its initialize method will automatically run immediately before main. If a lot of cleanup is required, this can go in its terminate class method. Again assuming the application
class is the last class defined, its terminate method will automatically run
immediately after main. Methods to
act as event handlers can also be defined in the application class, then
wrapped and assigned to the correct instances in the initialize method.
When only a simple application class is needed, Method Euphoria can create it for you. Use start_program in the place of main_program, then code your main program logic. Follow your main program logic with end_program to do cleanup and terminate your program. Internally Method Euphoria will treat all code between start_program and end_program as if it were included in the class ME_Kernel.Program's main class method and Me_Kernel.Program were the application class.
Thanks to Andy Serpa for the start_program/end_program idea.
STANDARD CLASS LIBRARY
Method Euphoria has a small but useful class library which is contained in the
following include files:
- me_containers.e: Containers such as stacks, queues, and
self-sorting containers. Also provides for the easy creation of new container
classes.
- me_counted.e: Instance counted classes, including the Singleton class.
- me_file_errors.e: Exceptions relating to file handling.
- me_math_errors.e: Exceptions relating to mathematical
operations.
- me_misc_errors.e: Other
useful exceptions
- me_variables.e: Reference variables and constants, with
events.
- me_widgets.e: Visual Basic style collections and components
for building widgets.
Version numbering of the Standard Class Library conforms to Method Euphoria. All
include files in the Library will have the same version number as the current
version of Method Euphoria.
Each of the include files above defines a subpackage of
the ME_Std_Lib package. The method_euphoria.e file defines Entity, Interface, Exception, Method_Wrapper, and several exceptions in the package ME_Kernel. For convenience, these are documented as part of the Standard Class Library as well. The file me_std_lib.e can be used to include the entire
library.
The
Standard Class Library documentation can be found here.
DEMO PROGRAMS
Five demo programs are included:
- demo.ex demonstrates some of the containers in the Standard Class Library.
- event.ex illustrates some abstract event handling.
- globals.ex is a
working utility that extracts and sorts all the global symbols from a Euphoria
code file.
- savetest.ex demonstrates saving and restoring entities using a text file.
- speedtst.ex provides some benchmarks--adapted from Rod Jackson's speed test for Quartz.
- tasking.ex demonstrates Method Euphoria's implmentation of task switching.
COMPATIBILITY
Method Euphoria 3.0.0 is fully backward compatible with Method Euphoria 2.0.1.
Method Euphoria 2.0.1 is fully backward compatible with Method Euphoria 2.0.0 with the exception that any code relying on the repaired bugs will break.
Method Euphoria 2.0.0 is largely backward compatible with Method Euphoria 1.4.0 and later versions, but several features have been redesigned and may introduce incompatibilities.
Significant changes have been made to the runtime routines: most errors throw exceptions rather than causing fatal errors. (For example, attempting to call an unrelated class's private method will cause Access_Denied to be thrown.) This may cause bugs in programs which rely on these errors being fatal.
The serialization feature has been completely redesigned. Serialized data from previous versions can be read, but custom serialization methods must be rewritten.
The internal representation of entity handles has been changed. Programs which rely on the internal representation of entity handles will need to be rewritten.
Method Euphoria 1.4.0 changed the exception model: in previous versions it was illegal to call a method while an exception was pending. This provides the programmer with greater flexibility, but may cause bugs in programs that rely on a crash occuring if a method is called with a pending exception. Apart from this, version 1.4.0 is fully backward compatible with previous versions.
Method Euphoria is fully compatible with all Euphoria 2.5 standard include files.
Though much of the code base of Method Euphoria is derived from Diamond, Method
Euphoria is not compatible with Diamond.
Method Euphoria makes use of Euphoria 2.5's crash_routine, consequently it will not run on earlier versions.
Method Euphoria is not compatible with the Euphoria 2.5 Tasking Interpreter. A compatible Method Euphoria will be provided for the Euphoria 3.0 alpha release.
END USER LICENSE AGREEMENT
Method Euphoria consists of all files contained in method_euphoria.zip.
Method Euphoria is freeware. Method Euphoria is released for private, public,
and commercial use subject to these conditions:
- All distributions of Method Euphoria, modifications of Method Euphoria, or programs
incorporating Method Euphoria shall include this End User License Agreement,
the Disclaimer, and proper authorship credit.
- All distributions of Method Euphoria, modifications of Method Euphoria, or programs
incorporating Method Euphoria shall be free of charge; but you may charge a
sufficient sum to recover the cost of the distribution media.
- You may freely modify Method Euphoria, but all distributions of modifications of
Method Euphoria must contain notice that you have made modifications and the
general nature of these modifications.
- You may incorporate Method Euphoria, either as-is or modified, into a larger
program. You may distribute your program if you comply with conditions 1, 2,
and 3 (if applicable).
- If you wish to sell a program which incorporates Method Euphoria, whether
as-is or modified, you may do so if you comply with conditions 1 and 3 (if
applicable). Condition 2 is waived if and only if your program's purpose is
clearly distinct from Method Euphoria's own purpose: the provision of Object
Oriented Programming services for the Euphoria language. [Examples: A business
application or a game incorporating Method Euphoria may be sold. A program
which prints "Hello World" incorporating Method Euphoria may not--the
program is clearly a ruse to evade condition 2.]
- You have unlimited rights to create new classes for use with Method Euphoria and to
copy, distribute and sell such classes, subject to the requirement that you do
use any combination of words indicating my endorsement of your classes or asserting any
kind of official status of your classes anywhere in your code or documentation. This prohibiton includes but is not limited to using the package names ME_Kernel and ME_Std_Lib (including variations in case and or/spelling).
- Condition 6 does not apply to classes submitted to me and accepted for inclusion in
official Method Euphoria libraries. Any class submitted to me and accepted will
be distributed free of charge (with full authorship credit) in future releases
of Method Euphoria. If you wish to sell a class, don't submit it for inclusion
in an official library.
DISCLAIMER
Method Euphoria is released without warranty of any kind whatsoever, whether express
or implied. The author is not responsible for any damages arising from the use
of this software, whether direct or indirect, incidental or consequential.
USE AT YOUR OWN RISK
ALPHABETICAL LISTING OF GLOBAL ROUTINES, VARIABLES, AND CONSTANTS
The syntax convention for routines is to show the return value (for functions and
types) and the parameters as type names with digits to distinguish them:
object1, integer2, entity3, etc. All errors are listed except type clashes and
illegal program contexts. Context indicates the legal program contexts for the
routine; if it is omitted, all contexts are legal.
A
B C D E F
G H I J K L M N O
P Q R S T U V W X Y Z
boolean
- Variety
- type
- Syntax
- boolean1=boolean(object1)
- Description
- Returns TRUE if object1 is TRUE or FALSE; otherwise
returns FALSE.
call_method
- Variety
- function
- Syntax
- object1=call_method(entity1,identifier1,object2)
- Context
- method
- Description
- Calls the appropriate method of entity1's class with entity1 as its target. If entity1 is an instance, an
instance method is called; if a class, class method is called. Identifier1
gives the name of the method and the parameters are contained in object2. If
object2 is an atom or an entity, it is wrapped in a one-element
sequence. If fewer parameters are passed than required by the method’s definition (see method), missing parameters are passed as
the special value NOTHING. If there
are more parameters than required, the excess parameters are discarded unless
the definition specifies a parameter array: then they are passed as a single
sequence. Returns the method's return value. If an attempt is made to call a method which is not defined by entity1's class, entity1's undefined_method instance or class method will be called automatically instead if one is defined. If entity1 is an instance, the instance method will be called; if a class, the class method. The name of the method which was attempted to be called is the first parameter, parameters to the attmpeted call are the second and subsequent parameters.
- Note
- Be careful of one parameter methods when passing a
sequence. For example: call_method(x,"do_this","ABC")
does not pass a single parameter "ABC" to x's do_this method--it passes three parameters 'a', 'b', and c' to x's do_this method. The correct syntax is
call_method(x,"do_this",{"ABC"})
- Errors
- Throws Invalid_Target if entity1 is a deleted instance.
- Throws Undefined_Method if the method to be called is not defined by entity1's class and that class does not define an undefined_method instance or class method (as appropriate).
- Throws Access_Denied if the currently executing method has inadequate access rights to call the method; or the method is the instance method serialize, deserialize or undefined_method; or the class method initialize, terminate or undefined_method.
call_super
- Variety
- function
- Syntax
- object1=call_super(object2)
- Context
- method
- Description
- Calls an overridden superclass method of the currently
executing method, passing object2 as the parameters as in
call_method. The target of the currently executing method will be the target of the superclass method.
Returns the overridden method’s return value. If the currently execting method does not override a superclass method, the superclass' undefined_method instance or class method will be called automatically instead if one is defined. If the target is an instance, the instance method will be called; if a class, the class method. The name of the method which was attempted to be called is the first parameter, parameters to the attmpeted call are the second and subsequent parameters.
- Errors
-
- Throws Invalid_Target if the target of the currently executing method has been deleted.
- Throws Undefined_Method if the currently executing method does not override a superclass method and the superclass does not define an undefined_method instance or class method (as appropriate).
- Throws Access_Denied if the overridden method is private or is the instance method serialize or deserialize.
cancel_serialize
- Variety
- procedure
- Syntax
- cancel_serialize()
- Context
- method
- Description
- Cancels the serialization of the current instance, but allows the serialization of any instance it is contained in to continue. If no serialization is in progress, nothing happens.
catch
- Variety
- function
- Syntax
- boolean1=catch(class1)
- Context
- method
- Description
- If class1 is the same exception as the pending
exception or a superclass of the pending exception,
returns TRUE and clears the pending exception; otherwise returns FALSE.
Returns FALSE if no exception is pending.
- Note
- Since all exceptions are direct or indirect subclasses of
Exception, catch(Exception) will catch any exception.
caught
- Variety
- function
- Syntax
- exception1=caught()
- Context
- method
- Description
- Returns the exact exception processed by catch if called within the method which caught the exception and no other exception has been thrown; otherwise returns NOTHING.
CLASS
- Variety
- constant
- Description
- Used in property,
method, null_method, or super_method to
specify a class property or method.
class
- Variety
- function
- Syntax
- class1=class(identifier1,class2,object1)
- Context
- initialization
- Description
- Begins the definition of a class with the name
identifier1. Class2 is the superclass. Object1 is an interface or a
sequence of interfaces (which may be empty), designating the interface or
interfaces to be implemented by the class. If object1 is an empty sequence, no interfaces are implemented.
- Note
- It is strongly recommended to assign class1 to a global
constant.
- Errors
-
Program termination if identifier1
duplicates an existing class name in the same package, object1 is not an
interface or a sequence of interfaces, or object1 contains
duplicate interfaces.
class_entity
- Variety
- type
- Syntax
- boolean1=class_entity(object1)
- Description
- Returns TRUE if object1 is a class; returns FALSE if
object1 is an instance or is not an entity.
class_name
- Variety
- function
- Syntax
- string1=class_name(object1)
- Description
- If object1 is a class, an instance, or a deleted entity,
returns its class name. If object1 is a class name, returns the fully qualified class name. If object1 is not an entity or a class name, returns an empty string.
CURRENT_VERSION
- Variety
- constant
- Description
- The current Method Euphoria version in sequence form:
{2,0,1}
debug_file
- Variety
- procedure
- Syntax
- debug_file()
- Description
- Creates a debug file me.err in the current directory listing:
- The error message if
called from fatal_error.
- The currently executing method and the methods which called it (if applicable), including any exceptions pending or caught in each method.
- A detailed listing of each class in the program.
- A listing or registered types in the program.
- Note
- Called by fatal_error.
deleted_entity
- Variety
- type
- Syntax
- boolean1=deleted_entity(object1)
- Description
- Returns TRUE if object1 is an instance which has been
deleted; returns FALSE if object1 is an instance which has not been
deleted, a class, or is not an entity.
deserialize
- Variety
- function
- Syntax
- object1=deserialize(string1)
- Context
- method
- Description
- String1 is a coded byte string created by serialize or the name of a file created by serialize.
Restores and returns the encoded object, if possible; if the deserialization fails, throws Deserialize_Error unless an exception was throw during deserialization and returns NOTHING. If the deserialization fails, any instances created by the deserialization are deleted. See Serialization for details.
- Note
- Only one serializtion or deserialization may be in progress at a time. Method Euphoria treats deserialize as a method call: a call to a hypothecial deserialize class method of the Entity class is placed on the program stack and will appear in error messages and the debug file.
end_class
- Variety
- procedure
- Syntax
- end_class()
- Context
- class definition
- Description
- Ends the current class definition and verifies the
definition.
- Errors
- Program termination if the class implements
an interface, and the class does not define (directly or by inheritance)
a public method specified by the interface.
end_package
- Variety
- procedure
- Syntax
- end_package()
- Context
- initialization
- Description
- Ends the current package.
- Errors
- Program termination if no current package
is defined.
end_program
- Variety
- procedure
- Syntax
- end_program()
- Context
- method
- Description
- End the program. The terminate class method is called for each class as in main_program.
- Note
- Intended for use with start_program, but can also be used in programs started via main_program.
entity
- Variety
- type
- Syntax
- boolean1=entity(object1)
- Description
- Returns TRUE if object1 is an entity (other than a deleted
instance), otherwise FALSE.
error_screen_width
- Variety
- procedure
- Syntax
- error_screen_width(object1)
- Description
- Sets the width of the error screen for formatting of
termination messages issued by fatal_error to
object1. If object1 is not an integer or is less than 20 the
setting is unchanged. (The initial width is 80.)
event
- Variety
- procedure
- Syntax
- event(identifier1,integer1,integer2)
- Context
- class definition
- Description
- Defines an event named identifier1 in the class currently
being defined. Integer1 specifies PUBLIC, PROTECTED,
or PRIVATE link access for the event; integer2 specifies PUBLIC, PROTECTED, or PRIVATE raise access for the event. For an event named x, an instance property also named x will be created to hold the list of event handlers. Two accessor methods will be created (get_x and set_x). An instance method
also named x will be created to allow raising the event.
- Errors
- Program termination if:
identifer1 duplicates an instance property name of the class or of any of its superclasses; integer1 is not PUBLIC, PROTECTED, or PRIVATE; or integer2 is not PUBLIC, PROTECTED, or PRIVATE.
exception
- Variety
- function
- Syntax
- Class1=exception(identifier1,class2)
- Context
- initialization
- Description
- Defines an exception with the name identifier1. Class2 is
an exception which designates the superclass. Returns the new exception's handle.
- Note
- It is strongly recommended to assign class1 to a global
constant.
- Errors
- Program termination if identifier1 duplicates an existing class name in the same package or class2 is not an exception.
extends
- Variety
- function
- Syntax
- boolean1=extends(object1,object2)
- Description
- Returns TRUE if object1 is a class and object2 is a
superclass of object1, or if object1 and object2 are the same class;
otherwise returns FALSE.
failure
- Variety
- function
- Syntax
- boolean1=failure()
- Context
- method
- Description
- Returns TRUE if an exception is currently pending,
otherwise FALSE.
FALSE
- Variety
- constant
- Description
- The integer 0, used as a boolean value.
fatal_error
- Variety
- procedure
- Syntax
- fatal_error(string1)
- Description
- Terminates the program with an error message. Word wraps the
error message based on width of the error screen; this defaults to 80, and
can be set by error_screen_width. Also calls debug_file. In method context, also cause any class terminate methods to be called as in main_program; but if fatal_error is called from a class' initialize method, terminate will only be called for that class and any previously-defined classes.
The error message consists of:
- The text in string1 prefaced by "METHOD EUPHORIA 2.0.1 FATAL ERROR"
- A list of currently pending methods (if any),including any exceptions pending in or caught by each method.
- An indication that the debug file me.err was created or could not be created.
- Note
- If fatal_error is called from a class' terminate method when the method was called automatically by fatal_error, the call is ignored.
get_class
- Variety
- function
- Syntax
- object1=get_class(object2)
- Description
- If object2 is an instance or a deleted entity, returns the
handle of the entity's class. If object2 is a class, returns object2. If object2 is a string specifying the full name of a class or a the partial name of a class defined
in the current package, returns the class entity. Otherwise, returns NOTHING.
get_property
- Variety
- function
- Syntax
- object1=get_property(entity1,identifier1)
- Context
- method
- Description
- If entity1 is an instance, returns the value of the instance property named identifier1 of the instance. If entity1 is a class, returns the value of the class property named identifier1 of the class.
- Errors
-
- Throws Invalid_Target if entity1 is a deleted instance.
- Throws Undefined_Property if the property to be read is not defined by entity1's class, directly or by inheritance.
- Throws Access_Denied if the currently executing method was not defined by the same class which defined the property.
identifier
- Variety
- type
- Syntax
- boolean1=identifier(object1)
- Description
- Returns TRUE if object1 is a string which is a valid Euphoria identifier: the first character is a letter and all of the other characters are letters, digits, and underscores; otherwise FALSE.
implements
- Variety
- function
- Syntax
- boolean1=implements(object1,object2)
- Description
- Returns
TRUE if object1 is an class, object2 is an interface, and object1 implements
that interface, directly or by inheritance; otherwise returns FALSE.
INSTANCE
- Variety
- constant
- Description
- Used in property,
method, null_method, or super_method to
specify an instance property or method.
instance_entity
- Variety
- type
- Syntax
- boolean1=instance_entity(object1)
- Description
- Returns
TRUE if object1 is an instance which has not been deleted; returns FALSE if
object1 is an instance which has been deleted, is a class, or is
not an entity.
instance_of
- Variety
- function
- Syntax
- boolean1=instance_of(object1,object2)
- Description
- Returns
TRUE if object1 is an instance and object2 is object1’s
class or a superclass of object1’s class; otherwise returns FALSE.
interface
- Variety
- function
- Syntax
- class1=interface(identifier1,object1,object2,object3)
- Context
- initialization
- Description
- Defines
an interface named identifier1. Object1 is an interface or a (possibly empty)
sequence of interfaces, which are the superclasses of the new interface. If
object1 is an empty sequence, Interface is the superclass. Object2 and object3 are single identifiers or
(possibly empty) sequences of identifiers naming methods to be implemented by
classes which implement the interface; object2 is for instance methods,
object3 is for class methods.
- Note
- It
is strongly recommended to assign class1 to a global constant.
- Errors
- Program
termination if identifier1 duplicates an existing class name in the same package,
object1 itself or any element of object1 (if it is a sequence) is not an
interface, object1 contains duplicate interfaces (including an interface and one or more of its superclasses is redundant but legal), or object2 or object3 contain duplicated methods.
last
- Variety
- function
- Syntax
- entity1=last()
- Context
- method
- Description
- Returns
the target of the method which called currently executing method. Returns NOTHING if the currently executing method was not called by another method.
last_class
- Variety
- function
- Syntax
- class1=last_class()
- Context
- method
- Description
- Returns
the class of the target of the method which called the currently executing method. Returns NOTHING if the currently excuting method was not called by another method.
- Note
- Syntactic sugar for get_class(last()). Intended for instance methods; in class methods,
last_class is legal but redundant, having the same value as last.
last_method
- Variety
- function
- Syntax
- string1=last_method()
- Context
- method
- Description
- Returns
the name of the method which called the currently executing method. Returns an empty string if the currently excuting method was not called by another method.
main_program
- Variety
- procedure
- Syntax
- main_program(class1)
- Context
- initialization
- Description
- Terminates
initialization context, does final verification of classes, begins running
the program. Automatically calls the initialize class method for each class that defines one, in the order in which the classes were defined.
Automatically calls the main class
method of class1. Automatically calls
the terminate class method of each class that defines one, in the reverse order of which the classes were defined. These method calls ignore exceptions.
- Errors
- Program
termination if class1 does not define a main class method.
make_sequence
- Variety
- function
- Syntax
- sequence1=make_sequence(object1)
- Context
- method
- Description
- If object1 is an atom or an entity, returns a one element sequence with object1 as the element; otherwise returns object1.
method
- Variety
- procedure
- Syntax
- method(identifier1,integer1,integer2,integer3,object1)
- Context
- class definition
- Description
- Defines
a method named identifier1 in the class currently being defined. Integer1 is
INSTANCE or CLASS to specify an instance or class method. Integer2 specifies PUBLIC, PROTECTED, or PRIVATE access. Integer3 is the
parameter count for the method. A negative parameter count may be used: this
specifies a parameter array. If for example the parameter count is -4, then
when the method is called with four or more parameters, all parameters after
the first three are concatenated into a sequence and assigned to the method’s
fourth parameter. If the method is called with three or fewer parameters, the
fourth parameter will be an empty sequence. If the method is implemented as a function, object1 is the routine id of the function. If the method is implemented as a procedure, object1 is a one- or two-element sequence. The first element is the routine id of the procedure. The second element if present is the method's return value; if absent the return value is NOTHING.
- Errors
- Program termination if identifer1 duplicates an instance method name or class method name (as the case may
be) of the class; integer1 is not INSTANCE or CLASS; integer2 is not PUBLIC, PROTECTED, or PRIVATE; the method overrides a superclass method and integer2 specifies more
restrictive access than the overridden method; or object1 is not formatted as above.
NIL
- Variety
- constant
- Description
- The integer 0 used in the sense of "no meaningful data".
NONE
- Variety
- constant
- Description
- The empty sequence. A notational convenience, particularly when a sequence is intended as a list.
NOTHING
- Variety
- constant
- Description
- A special value used to represent a missing method parameter, as a return value for a method which is logically a procedure, and in certain error reporting
situations, such as a failed constructor call.
null_method
- Variety
- procedure
- Syntax
- null_method(identifier1,integer1,integer2,object1)
- Context
- class definition
- Description
- Defines a null method (a method which does nothing) named identifier1 in the class currently being defined. Integer1 is INSTANCE or
CLASS to specify the an instance or class method. Integer2 specifies PUBLIC,
PROTECTED, or PRIVATE access. Object1 is the value which the method returns.
- Note
- Syntactic sugar for using method to accomplish the purpose.
OPTIONAL
- Variety
- constant
- Description
- Used in validate to indicate an optional parameter. Equal to FALSE.
package
- Variety
- procedure
- Syntax
- package(identifier1)
- Contexts
- initialization
- Description
- Defines a package named identifier1. All classes and types defined until the next end_package is encountered will be
part of this package. Packages may be nested: if a package is encountered again before an end_package, this will define a subpackage.
pending
- Variety
- function
- Syntax
- exception1=pending()
- Context
- method
- Description
- Returns the exact exception currently pending; returns
NOTHING if there is none.
PRIVATE
- Variety
- constant
- Description
- Used in property, method, or event
to specify private access.
property
- Variety
- procedure
- Syntax
- property(identifier1,integer1,integer2,object1,object2)
- Context
- class definition
- Description
- Defines a property named identifier1 in the class currently being defined. Integer1 is INSTANCE or CLASS to specify the type of property. Integer2 may be PUBLIC or PROTECTED: this specifies that a getter method with the specified access will be automatically generated. If the property is named x, the method will be named get_x. If integer2 is PRIVATE, no getter method will be generated. Object1 may be PUBLIC, PROTECTED, or PRIVATE, as for integer2. This will generate a setter method named set_x unless object1 is
PRIVATE. Object1 may also be a two or three element sequence. This will result in the generation of a setter method which performs type checking. The first element must be PUBLIC or PROTECTED to specify access. If object1 is a sequence, the second element or the second and third elements must be a valid second parameter for
validate.
Object2 is the initial value of the class property of the class and of its subclasses, or the initial value of the instance property for each newly-created instance of the class and of its subclasses, as the case may be.
- Errors
- Program termination if identifier1 duplicates an instance property name or class property name (as the case
may be) of the class or of any of its superclasses; integer1 is not INSTANCE or CLASS; interger2 is not PUBLIC, PROTECTED, or PRIVATE; object1 is not formatted as above.
PROTECTED
- Variety
- constant
- Description
- Used in property,
method, or event to specify protected access.
PUBLIC
- Variety
- constant
- Description
- Used in property,
method, or event to specify public access.
register_type
- Variety
- procedure
- Syntax
- register_type(identifier1,integer1)
- Contexts
- initialization
- Description
- Defines a type named identifier1 for
use by validate. Integer1 is the routine id of the type.
- Errors
- Program termination if identifier1 duplicates a type name in the same package.
REQUIRED
- Variety
- constant
- Description
- Used in validate to indicate a required parameter. Equal to TRUE.
rethrow
- Variety
- procedure
- Syntax
- rethrow()
- Contexts
- method
- Description
- Syntactic sugar for throw(caught()). Throws the last exception processed by catch, does nothing if caught would have returned NOTHING. See throw.
serialize
- Variety
- function
- Syntax
- string1=serialize(object1,object2)
- Context
- method
- Description
- Transforms object1 into a coded byte string. If object2 it is a non-empty string, it is treated as a file name. This file is created and the coded byte string will be written to it. The file name will be returned. If object2 is an empty
string or is not a string, the coded byte string itself will be returned. If the serialization fails, the file (if applicable) is deleted. Throws
Serialize_Error unless an exception was thrown during serialization. Returns the empty sequence.
See Serialization for details.
- Note
- Only one serialization or deserialization may be in progress at a time. Method Euphoria treats serialize as a method call: a call to a hypothecial serialize class method of the Entity class is placed on the program stack and will appear in error messages and the debug file.
serialized
- Variety
- function
- Syntax
- object1=serialized()
- Context
- method
- Description
- If a serialization is in progress, returns a shallow copy of the instance being serialized. This can be modified without affecting the original instance. If no serialization is in progress, returns NOTHING. See Serialization for details.
set_property
- Variety
- procedure
- Syntax
- set_property(entity1,identifier1,object1)
- Context
- method
- Description
- If entity1 is an instance, sets the instance property named identifier1 of the instance. If entity1 is a class, sets the class property named identifier1 of the class. Object1 is the value to which the property is set.
- Errors
- Throws Invalid_Target if entity1 is a deleted instance.
- Throws Undefined_Property if the property to be written is not defined by entity1's class, directly or by
inheritance.
- Throws Access_Denied if the currently executing method was not defined by the same class which
defined the property.
start_program
- Variety
- procedure
- Syntax
- start_program()
- Context
- initialization
- Description
- Starts the program. The initialize class method is called for each class as in main_program, then all code until end_program is encountered is executed as if it were included in the class ME_Kernel.Program's main class method and ME_Kernel.Program were the parameter of main_program.
string
- Variety
- type
- Syntax
- boolean1=string(object1)
- Description
- Returns TRUE if object1 is a string; otherwise
returns FALSE.
success
- Variety
- function
- Syntax
- boolean1=success()
- Context
- method
- Description
- Returns
TRUE if no exception is currently pending, otherwise FALSE.
super_method
- Variety
- procedure
- Syntax
- super_method(identifier1,integer1)
- Context
- class definition
- Description
- Overrides a superclass method named identifier1 to make it public. Integer1 is INSTANCE or CLASS to specify an instance or class method.
- Note
- Syntactic sugar for using method to accomplish the purpose.
this
- Variety
- function
- Syntax
- entity1=this()
- Context
- method
- Description
- Returns
the target of the currently executing method.
this_class
- Variety
- function
- Syntax
- class1=this_class()
- Context
- method
- Description
- Returns
the class of the target of the currently executing method.
- Note
- Syntactic sugar for get_class(this()). Intended for instance methods; in class methods,
this_class is legal but redundant, having the same value as this.
this_method
- Variety
- function
- Syntax
- identifier1=this_method()
- Context
- method
- Description
- Returns
the name of the currently executing method.
throw
- Variety
- procedure
- Syntax
- throw(class1)
- Contexts
- method
- Description
- Sets the pending exception to class1, which must be an exception.
- Errors
- Program
termination if an exception is already pending.
TRUE
- Variety
- constant
- Description
- The
integer 1 used as a boolean.
type_specifier
- Variety
- type
- Syntax
- boolean1=type_specifier(object1)
- Description
- Returns TRUE if object1 is a valid second parameter for validate; otherwise returns FALSE.
validate
- Variety
- procedure
- Syntax
- validate(object1,string1,boolean1)
OR
validate(object1,{identifier1,class1},boolean1)
- Context
- method
- Description
- In the first syntax, checks if object1 belongs to the type designated by string1, which is the name of a registered type (see register_type). If the type check is successful, returns. If the type check fails, throws Type_Check_Failure. If string1 is
neither the full name of a type nor the partial name of a type defined in the current package (the package in which the class which defined the currently executing method was defined), throws Invalid_Type.
In the second syntax, identifier1 must be “entity”, “instance” or “class”. If object1 is not an entity of the variety specifed by identifier1, throws Type_Check_Failure. Returns with no exception if class1 is object1's class, is a superclass of object1’s class, or object1’s class implements (directly or by inheritance) class1 if it is an interface; otherwise throws Type_Check_Failure. If the second parameter is not formatted correctly, throws Invalid_Type.
In either syntax, if boolean1 is REQUIRED,
throws Missing_Parameter if object1 is NOTHING. If boolean1 is OPTIONAL, returns with no exception if object1 is NOTHING.
VOID
- Variety
- variable
- Description
- Used to discard unwanted parameters and unwanted return values, particularly the return values of a method which is logically a procedure and has no meaningful return value. Do not use VOID for
any other purpose.
- Note
- Do
not attempt to read VOID: its value is unknown as it is used internally and is used by many methods.